typed-query-selector

What is typed-query-selector?

The typed-query-selector npm package provides a way to use TypeScript to query DOM elements with type safety. It ensures that the elements you query from the DOM are correctly typed, reducing runtime errors and improving code quality.

What are typed-query-selector's main functionalities?

Type-safe querySelector

This feature allows you to use TypeScript's type assertions to ensure that the element you are querying is of the expected type. This reduces the risk of runtime errors due to incorrect element types.

const button = document.querySelector('button') as HTMLButtonElement;

Type-safe querySelectorAll

Similar to querySelector, this feature allows you to use TypeScript's type assertions to ensure that the elements you are querying are of the expected type. This is particularly useful when working with collections of elements.

const divs = document.querySelectorAll('div') as NodeListOf<HTMLDivElement>;

Type-safe event listeners

This feature ensures that event listeners are correctly typed, reducing the risk of runtime errors due to incorrect event target types.

const button = document.querySelector('button') as HTMLButtonElement;
button.addEventListener('click', (event) => {
  console.log(event.target); // event.target is correctly typed as HTMLButtonElement
});

Other packages similar to typed-query-selector

typescript

TypeScript itself provides type safety for DOM manipulation, but it requires manual type assertions. The typed-query-selector package simplifies this process by providing a more intuitive API.

ts-query

The ts-query package offers similar functionality to typed-query-selector, providing type-safe DOM querying. However, it may have a different API and feature set, so it's worth comparing the two to see which one better fits your needs.

typed-dom

The typed-dom package provides type-safe DOM manipulation and querying, similar to typed-query-selector. It also includes additional utilities for working with the DOM in a type-safe manner.

README

🏷 Typed querySelector

querySelector and querySelectorAll functions with better typing by leveraging TypeScript 4.1 template literal type.

💿 Install

npm i -D typed-query-selector

🍉 Usage

Automatic shim

All you need to do is to import this module, then the querySelector and querySelectorAll function will be enhanced.

This module only works at type level and doesn't have any runtime code.

import 'typed-query-selector'

document.querySelector('div#app') // ==> HTMLDivElement

document.querySelector('div#app > form#login') // ==> HTMLFormElement

document.querySelectorAll('span.badge') // ==> NodeListOf<HTMLSpanElement>

anElement.querySelector('button#submit') // ==> HTMLButtonElement

Playground

The example above assumes you're using bundlers or build tools with transpilers, however, sometimes this may not match your situation. For example, running tsc or Babel out of bundlers. In this case, you can import this library like this:

import type {} from 'typed-query-selector'

document.querySelector('div#app') // ==> HTMLDivElement

Playground

This looks ugly but it works.

If you aren't going to use ES Modules you can modify your tsconfig.json, however this is NOT recommended, unless you know what you're doing.

{
  "compilerOptions": {
    "types": ["typed-query-selector"]
  }
}

Strict mode

Available in v2.3+

In strict mode, the selector parser will perform additional syntax checks on input string. If there're syntax errors, return type will be never instead of Element.

Example usage:

import 'typed-query-selector/strict'

const element = document.querySelector('div[test') // return `never`

This feature won't be enabled by default and you can opt-in. If you want to enable this, change import entry:

- import 'typed-query-selector'
+ import 'typed-query-selector/strict'

That's all. If you pass an invalid selector, because it returns never, TypeScript will prevent you from accessing properties/methods on element or using element at somewhere.

Note that it doesn't guarantee that it can detect every kind of syntax errors, since such parser will become very complex and compilation performance may go bad.

Use the parser

If you just want to use the selector parser itself, we've exported for you:

import type {
  ParseSelector,
  StrictlyParseSelector, // or use the strict parser
} from 'typed-query-selector/parser'

type MyElement = ParseSelector<'form#login'>

Playground

Please note that you should import typed-query-selector/parser, not typed-query-selector. This is safe because this import doesn't patch to the querySelector and querySelectorAll function.

Sometimes, you may want to specify another fallback type (such as HTMLElement, not default Element type) when failed to parse selector or failed to look up, you can pass a fallback type as the second type parameter:

Available in v2.4+

import type { ParseSelector } from 'typed-query-selector/parser'

type MyElement = ParseSelector<'unknown-tag', HTMLElement> // ==> HTMLElement

Playground

💡 Supported Use Cases

With class, ID, pseudo class or attribute

import 'typed-query-selector'

document.querySelector('div.container') // ==> HTMLDivElement

document.querySelector('div#app') // ==> HTMLDivElement

document.querySelector('input[name=username]') // ==> HTMLInputElement

document.querySelector('input:first-child') // ==> HTMLInputElement

Playground

Even mix them:

import 'typed-query-selector'

document.querySelector('input.form-control[name=username]') // ==> HTMLInputElement

Playground

And with :is() or :where():

Available in v2.5+

import 'typed-query-selector'

document.querySelector(':is(div#id, span.class[k=v])') // ==> HTMLDivElement | HTMLSpanElement

document.querySelector(':where(div#id, span.class[k=v])') // ==> HTMLDivElement | HTMLSpanElement

Playground

Combinators

import 'typed-query-selector'

document.querySelector('body div') // ==> HTMLDivElement

document.querySelector('body > form') // ==> HTMLFormElement

document.querySelector('h1 + p') // ==> HTMLParagraphElement

document.querySelector('h2 ~ p') // ==> HTMLParagraphElement

Playground

Grouping selectors

import 'typed-query-selector'

document.querySelector('div, span') // ==> HTMLDivElement | HTMLSpanElement

Playground

Fallback

Custom Elements

If you passed an unknown tag, it will fall back to Element.

import 'typed-query-selector'

document.querySelector('my-web-component') // ==> Element

However, you can override it by specifying a concrete type as a type argument.

document.querySelector<MyComponent>('my-web-component') // ==> MyComponent

Playground

Alternatively, you can use global augmentation and interface merging to extend HTMLElementTagNameMap with your custom elements.

declare global {
  interface HTMLElementTagNameMap {
    'my-web-component': MyComponent
  }
}

document.querySelector('my-web-component') // ==> MyComponent

Playground

Invalid selector

When passing an invalid selector which causes parsing error, it will fall back to Element.

import 'typed-query-selector'

document.querySelector('div#app >') // ==> Element

document.querySelector('div#app ?') // ==> Element

However, if you're using strict mode, all querySelector calls above will return never type. This can stop you from misusing it.

import 'typed-query-selector/strict'

const el = document.querySelector('div#app >')
el.className // TypeScript will report error when compiling

🔩 Technical Details

Why returns never in strict mode?

In runtime, if you pass an invalid selector string to querySelector or querySelectorAll function, it will throw an error instead of returning null or undefined or anything else. For details, please read TypeScript Handbook.

🔗 Related

• Type Gymnastics - Collection of wonderful TypeScript type gymnastics code snippets.

📃 License

MIT License

Copyright (c) 2020-present Pig Fang

Changelog

v2.12.0

• Added support of special case for custom pseudo element selector.